USB Time Utility Functions4

This section describes the functions for managing time within the context of USB frames. A USB frame is approximately a 1 ms unit of time. Approximately, because it may vary a few bit times.

USBDelay

The USBDelay function calls back through the normal completion mechanism when the specified number of frames have passed. There is up to an extra one frame delay to accommodate synchronizing with USB frames. For example, 0 frames delay means after the current frame, which could be up to 1 ms plus any other system delays.



 
OSStatus USBDelay(USBPB *pb);

Required fields in the USBPB parameter block for the USBDelay function are

--> pbLength: Length of parameter block
--> pbVersion: Parameter block version number
--> usbCompletion: The completion routine
--> usbRefcon: General-purpose value passed back to the completion routine
--> usbReference: A device, interface, or pipe reference which associates the call with a device
--> usbReqCount: Number of frames to delay
<-- usbActCount: Frame number at completion of delay
--> usbFlags: Callback at task time (kUSBTaskTimeFlag )

The usbFlags parameter can be used to request a call back at task time. A requested delay of kUSBNoDelay causes the call back to occur as soon as possible during system task time (as opposed to secondary interrupt time). Thus effecting a transition to task time.

There must be a valid USBReference passed in the usbReference field of the parameter block. If a nil value or a reference that does not match an existing device interface or pipe is passed in, the call returns immediately with an unknown device error.

If the device associated with this call is unplugged and its driver removed while this function call is pending, the function will not complete.

The USBDelay function returns the following error:

kUSBUnknownDeviceErr -6998 usbReference does not refer to a current device

USBGetFrameNumberImmediate

The USBGetFrameNumberImmediate function returns the current frame number for the specified device. The function completes synchronously and is the recommended function to use for making time calculations for a class driver. It can be called at any execution level. This function also supports multiple USB bus implementations.



 
OSStatus USBGetFrameNumberImmediate(USBPB *pb);

Required fields in the USBPB parameter block for the USBGetFrameNumberImmediate function are

--> pbLength: Length of parameter block
--> pbVersion: Parameter block version number
--> usbCompletion: The completion routine
--> usbRefcon: General-purpose value passed back to the completion routine
--> usbReference: Device, interface, or endpoint reference
--> usbReqCount: Size of buffer (0 or size of UInt64)
--> usbBuffer: Nil or pointer to a UInt64 structure for full 64 bits of frame data.
<-- usbActCount: Size of data returned
<-- usbFrame: Low 32 bits of the current frame number

In multiple USB bus configurations, each bus has an independent frame count. The USBGetFrameNumberImmediate function takes any device, interface, or endpoint reference as input and returns the current frame number for the bus on which that device, interface, or endpoint is connected.

The frame count for each bus is maintained internally by the USB software as a 64 bit value. The USBGetNextFrameNumberImmediate function allows a driver to get either the low 32 bits of this value in the parameter block, or the full 64 bit value in a UInt64 structure. To get the low 32 bits, specify a value of nil in usbBuffer and a value of 0 in usbReqCount . To get the full 64 bits, specify the size of the UInt64 structure in the usbReqCount field and pointer to an address of the structure in usbBuffer .

This function does not call the completion routine. However, a value is required in the usbCompletion field. kUSBNoCallBack can be specified as the completion routine.

The USBGetNextFrameNumberImmediate function returns the following error:

kUSBUnknownDeviceErr -6998 usbReference does not refer to a current device